home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tcl / AddErrInfo.man < prev    next >
Encoding:
Text File  |  1992-08-07  |  8.8 KB  |  312 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/AddErrInfo.man,v 1.9 92/06/15 08:15:39 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tcl_AddErrorInfo tcl
  189. .BS
  190. .SH NAME
  191. Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_UnixError, Tcl_CheckStatus \- record information about errors
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tcl.h>\fR
  195. .sp
  196. char *
  197. \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
  198. .sp
  199. .VS
  200. void
  201. \fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fR)
  202. .sp
  203. char *
  204. \fBTcl_UnixError\fR(\fIinterp\fR)
  205. .VE
  206. .SH ARGUMENTS
  207. .AS Tcl_Interp *message
  208. .AP Tcl_Interp *interp in
  209. Interpreter in which to record information.
  210. .AP char *message in
  211. Identifying string to record in \fBerrorInfo\fR variable.
  212. .AP char *element in
  213. .VS
  214. String to record as one element of \fBerrorCode\fR variable.
  215. Last \fIelement\fR argument must be NULL.
  216. .VE
  217. .BE
  218.  
  219. .SH DESCRIPTION
  220. .PP
  221. .VS
  222. These procedures are used to manipulate two global variables
  223. that hold information about errors.
  224. The variable \fBerrorInfo\fR holds a stack trace of the
  225. operations that were in progress when an error occurred, and
  226. is intended to be human-readable.
  227. The variable \fBerrorCode\fR holds a list of items that
  228. are intended to be machine-readable.
  229. The first item in \fBerrorCode\fR identifies the class of
  230. error that occurred (e.g. UNIX means an error occurred in
  231. a Unix system call) and additional elements in \fBerrorCode\fR
  232. hold additional pieces of information that depend on the class.
  233. See the Tcl overview manual entry for details on the various
  234. formats for \fBerrorCode\fR.
  235. .PP
  236. The \fBerrorInfo\fR variable is gradually built up as an
  237. error unwinds through the nested operations.
  238. Each time an error code is returned to \fBTcl_Eval\fR
  239. it calls the procedure \fBTcl_AddErrorInfo\fR to add
  240. additional text to \fBerrorInfo\fR describing the
  241. command that was being executed when the error occurred.
  242. By the time the error has been passed all the way back
  243. to the application, it will contain a complete trace
  244. of the activity in progress when the error occurred.
  245. .PP
  246. It is sometimes useful to add additional information to
  247. \fBerrorInfo\fR beyond what can be supplied automatically
  248. by \fBTcl_Eval\fR.
  249. \fBTcl_AddErrorInfo\fR may be used for this purpose:
  250. its \fImessage\fR argument contains an additional
  251. string to be appended to \fBerrorInfo\fR.
  252. For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR
  253. to record the name of the file being processed and the
  254. line number on which the error occurred;  for Tcl procedures, the
  255. procedure name and line number within the procedure are recorded,
  256. and so on.
  257. The best time to call \fBTcl_AddErrorInfo\fR is just after
  258. \fBTcl_Eval\fR has returned \fBTCL_ERROR\fR.
  259. In calling \fBTcl_AddErrorInfo\fR, you may find it useful to
  260. use the \fBerrorLine\fR field of the interpreter (see the
  261. \fBTcl_Interp\fR manual entry for details).
  262. .PP
  263. The procedure \fBTcl_SetErrorCode\fR is used to set the
  264. \fBerrorCode\fR variable.
  265. Its \fIelement\fR arguments give one or more strings to record
  266. in \fBerrorCode\fR:  each \fIelement\fR will become one item
  267. of a properly-formed Tcl list stored in \fBerrorCode\fR.
  268. \fBTcl_SetErrorCode\fR is typically invoked just before returning
  269. an error.
  270. If an error is returned without calling \fBTcl_SetErrorCode\fR
  271. then the Tcl interpreter automatically sets \fBerrorCode\fR
  272. to \fBNONE\fR.
  273. .PP
  274. \fBTcl_UnixError\fR sets the \fBerrorCode\fR variable after an error
  275. in a UNIX kernel call.
  276. It reads the value of the \fBerrno\fR C variable and calls
  277. \fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the
  278. \fBUNIX\fR format.
  279. In addition, \fBTcl_UnixError\fR returns a human-readable
  280. diagnostic message for the error (this is the same value that
  281. will appear as the third element in \fBerrorCode\fR).
  282. It may be convenient to include this string as part of the
  283. error message returned to the application in \fIinterp->result\fR.
  284. .PP
  285. It is important to call the procedures described here rather than
  286. setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
  287. \fBTcl_SetVar\fR.
  288. The reason for this is that the Tcl interpreter keeps information
  289. about whether these procedures have been called.
  290. For example, the first time \fBTcl_AppendResult\fR is called
  291. for an error, it clears the existing value of \fBerrorInfo\fR
  292. and adds the error message in \fIinterp->result\fR to the variable
  293. before appending \fImessage\fR;  in subsequent calls, it just
  294. appends the new \fImessage\fR.
  295. When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
  296. that \fBerrorCode\fR has been set;  this allows the Tcl interpreter
  297. to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return
  298. when \fBTcl_SetErrorCode\fR hasn't been called.
  299. .PP
  300. If the procedure \fBTcl_ResetResult\fR is called, it clears all
  301. of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR
  302. (but it doesn't actually modify the variables).
  303. If an error had occurred, this will clear the error state to
  304. make it appear as if no error had occurred after all.
  305. .VE
  306.  
  307. .SH "SEE ALSO"
  308. Tcl_ResetResult, Tcl_Interp
  309.  
  310. .SH KEYWORDS
  311. error, stack, trace, variable
  312.